home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 July: Mac OS SDK / Dev.CD Jul 96 SDK / Dev.CD Jul 96 SDK1.toast / Development Kits (Disc 1) / Apple Game Sprockets / Headers / NetSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-05-16  |  13.5 KB  |  559 lines  |  [TEXT/CWIE]
  1. /******************************************************************************
  2.  **                                                                              **
  3.  **     Module:        NetSprocket.h                                             **                        
  4.  **        Author(s):     Jamie Osborne                                              **
  5.  **                                                                             **
  6.  **     Purpose:     Apple Game Sprockets Networking                          **            
  7.  **                                                                              **
  8.  **                                                                              **
  9.  **     Copyright (C) 1996 Apple Computer, Inc.  All rights reserved.         **
  10.  **                                                                              **
  11.  **                                                                              **
  12.  *****************************************************************************/
  13.  
  14. #ifndef __NETSPROCKET__
  15. #define __NETSPROCKET__
  16.  
  17. #ifndef SystemSevenOrLater
  18. #define SystemSevenOrLater    1
  19. #endif
  20.  
  21. #if PRAGMA_ALIGN_SUPPORTED
  22. #pragma options align=power
  23. #endif
  24.  
  25. #pragma enumsalwaysint on
  26.  
  27. #ifndef __TYPES__
  28. #include <Types.h>
  29. #endif
  30.  
  31. #ifndef __OPENTRANSPORT__
  32. #include <OpenTransport.h>
  33. #endif
  34.  
  35. #ifndef __OPENTPTINTERNET__
  36. #include <OpenTptInternet.h>
  37. #endif
  38.  
  39. #define kNSpMaxPlayerNameLen        31
  40. #define kNSpMaxGroupNameLen            31
  41. #define kNSpMaxPasswordLen            31
  42. #define kNSpMaxGameNameLen            31
  43. #define kNSpMaxDefinitionStringLen    255
  44.  
  45.  
  46. /* NetSprocket basic types */
  47. typedef    struct NSpGamePrivate        *NSpGameReference;
  48. typedef    struct NSpProtocolPrivate    *NSpProtocolReference;
  49. typedef    struct NSpListPrivate        *NSpProtocolListReference;
  50. typedef struct NSPAddressPrivate    *NSpAddressReference;
  51. typedef SInt32                        NSpEventCode;
  52. typedef    SInt32                        NSpGameID;
  53. typedef    SInt32                        NSpPlayerID;
  54. typedef NSpPlayerID                    NSpGroupID;
  55. typedef UInt32                        NSpPlayerType;
  56. typedef SInt32                        NSpFlags;
  57.  
  58. /* Individual player info */
  59. typedef struct NSpPlayerInfo
  60. {
  61.     NSpPlayerID        id;
  62.     NSpPlayerType    type;
  63.     Str31            name;
  64.     UInt32            groupCount;
  65.     NSpGroupID        groups[kVariableLengthArray];
  66. } NSpPlayerInfo, *NSpPlayerInfoPtr;
  67.  
  68.     
  69. /* list of all players */
  70. typedef struct NSpPlayerEnumeration
  71. {
  72.     UInt32                count;
  73.     NSpPlayerInfoPtr    playerInfo[kVariableLengthArray];
  74. } NSpPlayerEnumeration, *NSpPlayerEnumerationPtr;
  75.  
  76.  
  77. /* Individual group info */
  78. typedef struct NSpGroupInfo
  79. {
  80.     NSpGroupID    id;
  81.     UInt32        playerCount;
  82.     NSpPlayerID    players[kVariableLengthArray];
  83. } NSpGroupInfo, *NSpGroupInfoPtr;
  84.  
  85.  
  86. /* List of all groups */
  87. typedef struct NSpGroupEnumeration
  88. {
  89.     UInt32            count;
  90.     NSpGroupInfoPtr    groups[kVariableLengthArray];
  91. } NSpGroupEnumeration, *NSpGroupEnumerationPtr;
  92.  
  93. /* Topology types */
  94. typedef enum 
  95. {
  96.     kNSpClientServer =     0x00000001
  97. } NSpTopology;
  98.  
  99. /* Game information */
  100. typedef struct NSpGameInfo
  101. {
  102.     UInt32        maxPlayers;
  103.     UInt32        currentPlayers;
  104.     UInt32        currentGroups;
  105.     NSpTopology    topology;
  106.     UInt32        reserved;
  107.     Str31        name;
  108.     Str31        password;
  109. } NSpGameInfo;
  110.     
  111.     
  112. /* Structure used for sending and receiving network messages */
  113. typedef struct NSpMessageHeader
  114. {
  115.     UInt32        version;    /* Used by NetSprocket.  Don't touch this */
  116.     SInt32        what;        /* The kind of message (e.g. player joined) */
  117.     NSpPlayerID    from;        /* ID of the sender */
  118.     NSpPlayerID    to;            /* (player or group) id of the intended recipient */
  119.     UInt32        id;            /* Unique ID for this message & (from) player */
  120.     UInt32        when;        /* Timestamp for the message */
  121.     UInt32        messageLen;    /* Bytes of data in the entire message (including the header) */
  122. } NSpMessageHeader;
  123.  
  124.  
  125. /* NetSprocket-defined message structures */
  126.  
  127. typedef struct NSpErrorMessage
  128. {
  129.     NSpMessageHeader    header;
  130.     OSStatus            error;
  131. } NSpErrorMessage;
  132.  
  133.  
  134. typedef struct NSpJoinRequestMessage
  135. {
  136.     NSpMessageHeader    header;
  137.     Str31                name;
  138.     Str31                password;
  139.     UInt32                type;
  140.     UInt32                customDataLen;
  141.     UInt8                customData[kVariableLengthArray];
  142. } NSpJoinRequestMessage;
  143.  
  144.  
  145. typedef struct NSpJoinApprovedMessage
  146. {
  147.     NSpMessageHeader    header;
  148. } NSpJoinApprovedMessage;
  149.  
  150.  
  151. typedef struct NSpJoinDeniedMessage
  152. {
  153.     NSpMessageHeader    header;
  154.     Str255                reason;
  155. } NSpJoinDeniedMessage;
  156.  
  157.  
  158. typedef struct NSpPlayerJoinedMessage
  159. {
  160.     NSpMessageHeader    header;
  161.     UInt32                playerCount;
  162.     NSpPlayerInfo            playerInfo;    
  163. } NSpPlayerJoinedMessage;
  164.  
  165.  
  166. typedef struct NSpPlayerLeftMessage
  167. {
  168.     NSpMessageHeader    header;
  169.     UInt32                playerCount;
  170.     NSpPlayerID            playerID;    
  171. } NSpPlayerLeftMessage;
  172.  
  173. typedef struct NSpHostChangedMessage
  174. {
  175.     NSpMessageHeader    header;
  176.     NSpPlayerID            newHost;
  177. } NSpHostChangedMessage;
  178.  
  179.  
  180. typedef struct NSpGameTerminatedMessage
  181. {
  182.     NSpMessageHeader    header;
  183. } NSpGameTerminatedMessage;
  184.  
  185.  
  186. /* Different kinds of messages.  These can NOT be bitwise ORed together */
  187. enum
  188. {
  189.     kNSpSendFlag_Junk =         0x00100000,        /* will be sent (try once) when there is nothing else pending */
  190.     kNSpSendFlag_Normal =         0x00200000,        /* will be sent immediately (try once) */
  191.     kNSpSendFlag_Registered =     0x00300000        /* will be sent immediately (guaranteed, in order) */
  192. };
  193.  
  194.  
  195. /* Options for message delivery.  These can be bitwise ORed together with each other,
  196.         as well as with ONE of the above */
  197. enum 
  198. {
  199.     kNSpSendFlag_FailIfPipeFull =     0x00000001,
  200.     kNSpSendFlag_SelfSend =         0x00000002,
  201.     kNSpSendFlag_Blocking =         0x00000004
  202. };
  203.  
  204.  
  205. /* Options for Hosting Joining, and Deleting games */
  206. enum
  207. {
  208.     kNSpGameFlag_DontAdvertise            =    0x00000001,
  209.     kNSpGameFlag_ForceTerminateGame     =     0x00000002
  210. };
  211.  
  212. /* Message "what" types */
  213. /* Apple reserves all negative "what" values (anything with bit 32 set) */ 
  214. enum 
  215. {
  216.     kNSpSystemMessagePrefix = 0x80000000,
  217.     kNSpError =                 kNSpSystemMessagePrefix | 0x7FFFFFFF,
  218.     kNSpJoinRequest =         kNSpSystemMessagePrefix | 0x00000001,
  219.     kNSpJoinApproved =         kNSpSystemMessagePrefix | 0x00000002,
  220.     kNSpJoinDenied =         kNSpSystemMessagePrefix | 0x00000003,
  221.     kNSpPlayerJoined =         kNSpSystemMessagePrefix | 0x00000004,
  222.     kNSpPlayerLeft =         kNSpSystemMessagePrefix | 0x00000005,
  223.     kNSpHostChanged =         kNSpSystemMessagePrefix | 0x00000006,
  224.     kNSpGameTerminated=     kNSpSystemMessagePrefix | 0x00000007
  225. };
  226.  
  227.  
  228. /* Special TPlayerIDs  for sending messages */
  229. enum
  230. {
  231.     kNSpAllPlayers =     0x00000000,
  232.     kNSpHostOnly =        0xFFFFFFFF
  233. };
  234.     
  235.  
  236. #ifdef __cplusplus
  237. extern "C" {
  238. #endif
  239.  
  240. /************************  Initialization  ************************/
  241.  
  242. OSStatus NSpInitialize(
  243.     UInt32                         inStandardMessageSize, 
  244.     UInt32                         inBufferSize, 
  245.     UInt32                         inQElements, 
  246.     NSpGameID                     inGameID, 
  247.     UInt32                         inTimeout);
  248.  
  249.  
  250. /**************************  Protocols  **************************/
  251.  
  252. /* Programmatic protocol routines */
  253. OSStatus NSpProtocol_New(
  254.     const char*                 inDefinitionString, 
  255.     NSpProtocolReference*        outReference);
  256.  
  257. void NSpProtocol_Dispose(
  258.     NSpProtocolReference         inProtocolRef);
  259.  
  260. OSStatus NSpProtocol_ExtractDefinitionString(
  261.     NSpProtocolReference         inProtocolRef, 
  262.     char*                        outDefinitionString);
  263.  
  264.  
  265. /* Protocol list routines */
  266. OSStatus NSpProtocolList_New(
  267.     NSpProtocolReference         inProtocolRef,
  268.     NSpProtocolListReference*    outList);
  269.  
  270. void NSpProtocolList_Dispose(
  271.     NSpProtocolListReference     inProtocolList);
  272.  
  273. OSStatus NSpProtocolList_Append(
  274.     NSpProtocolListReference     inProtocolList,
  275.     NSpProtocolReference         inProtocolRef);
  276.  
  277. OSStatus NSpProtocolList_Remove(
  278.     NSpProtocolListReference     inProtocolList, 
  279.     NSpProtocolReference         inProtocolRef);
  280.  
  281. OSStatus NSpProtocolList_RemoveIndexed(
  282.     NSpProtocolListReference     inProtocolList,
  283.     UInt32                         inIndex);
  284.  
  285. UInt32 NSpProtocolList_GetCount(
  286.     NSpProtocolReference         inProtocolList);
  287.  
  288. NSpProtocolReference NSpProtocolList_GetIndexedRef(
  289.     NSpProtocolListReference     inProtocolList,
  290.     UInt32                         inIndex);
  291.  
  292.  
  293. /* Helpers */
  294. NSpProtocolReference NSpProtocol_CreateAppleTalk(
  295.     ConstStr31Param             inNBPName,
  296.     ConstStr31Param             inNBPType, 
  297.     UInt32                         inMaxRTT,
  298.     UInt32                         inMinThruput);
  299.  
  300. NSpProtocolReference NSpProtocol_CreateIP(
  301.     InetPort                     inPort,
  302.     UInt32                         inMaxRTT,
  303.     UInt32                         inMinThruput);
  304.  
  305.  
  306. /***********************  Human Interface  ************************/
  307. typedef pascal Boolean (*NSpEventProcPtr) (EventRecord* inEvent);
  308.  
  309.  
  310. NSpAddressReference NSpDoModalJoinDialog(
  311.     ConstStr31Param             inGameType, 
  312.     ConstStr255Param             inEntityListLabel,
  313.     Str31                         ioName, 
  314.     Str31                         ioPassword, 
  315.     NSpEventProcPtr             inEventProcPtr);
  316.  
  317. Boolean NSpDoModalHostDialog(
  318.     NSpProtocolListReference     ioProtocolList, 
  319.     Str31                         ioGameName, 
  320.     Str31                         ioPlayerName,
  321.     Str31                         ioPassword, 
  322.     NSpEventProcPtr             inEventProcPtr);
  323.  
  324.  
  325. /*********************  Hosting and Joining  **********************/
  326.  
  327. OSStatus NSpGame_Host(
  328.     NSpGameReference*            outGame, 
  329.     NSpProtocolListReference     inProtocolList, 
  330.     UInt32                         inMaxPlayers, 
  331.     ConstStr31Param             inGameName, 
  332.     ConstStr31Param             inPassword,
  333.     ConstStr31Param             inPlayerName, 
  334.     NSpPlayerType                 inPlayerType, 
  335.     NSpTopology                 inTopology,
  336.     NSpFlags                     inFlags);
  337.  
  338. OSStatus NSpGame_Join(
  339.     NSpGameReference*            outGame, 
  340.     NSpAddressReference         inAddress, 
  341.     ConstStr31Param             inName,
  342.     ConstStr31Param             inPassword,
  343.     NSpPlayerType                 inType, 
  344.     void*                        inCustomData,
  345.     UInt32                         inCustomDataLen,  
  346.     NSpFlags                     inFlags);
  347.  
  348. OSStatus NSpGame_EnableAdvertising(
  349.     NSpGameReference             inGame, 
  350.     NSpProtocolReference         inProtocol, 
  351.     Boolean                     inEnable);
  352.  
  353. OSStatus NSpGame_Dispose(
  354.     NSpGameReference             inGame, 
  355.     NSpFlags                     inFlags);
  356.  
  357.  
  358. /**************************  Messaging  **************************/
  359.  
  360. OSStatus NSpMessage_Send(
  361.     NSpGameReference             inGame, 
  362.     NSpMessageHeader*            inMessage, 
  363.     NSpFlags                     inFlags);
  364.  
  365. NSpMessageHeader *NSpMessage_Get(
  366.     NSpGameReference             inGame);
  367.  
  368. void NSpMessage_Release(
  369.     NSpGameReference             inGame, 
  370.     NSpMessageHeader*            inMessage);
  371.  
  372. /* Helpers */
  373. OSStatus NSpMessage_SendTo(
  374.     NSpGameReference             inGame,
  375.     NSpPlayerID                    inTo,
  376.     SInt32                        inWhat, 
  377.     void*                        inData,
  378.     UInt32                        inDataLen, 
  379.     NSpFlags                     inFlags);
  380.     
  381.  
  382. /*********************  Player Information  **********************/
  383.  
  384. NSpPlayerID NSpPlayer_GetMyID(
  385.     NSpGameReference             inGame);
  386.  
  387. OSStatus NSpPlayer_GetInfo(
  388.     NSpGameReference             inGame, 
  389.     NSpPlayerID                 inPlayerID, 
  390.     NSpPlayerInfoPtr*            outInfo);
  391.  
  392. void NSpPlayer_ReleaseInfo(
  393.     NSpGameReference             inGame, 
  394.     NSpPlayerInfoPtr             inInfo);
  395.  
  396. OSStatus NSpPlayer_GetEnumeration(
  397.     NSpGameReference             inGame, 
  398.     NSpPlayerEnumerationPtr*    outPlayers);
  399.  
  400. void NSpPlayer_ReleaseEnumeration(
  401.     NSpGameReference             inGame, 
  402.     NSpPlayerEnumerationPtr     inPlayers);
  403.  
  404. UInt32 NSpPlayer_GetRoundTripTime(
  405.     NSpGameReference             inGame, 
  406.     NSpPlayerID                 inPlayer); 
  407.  
  408. UInt32 NSpPlayer_GetThruput(
  409.     NSpGameReference             inGame, 
  410.     NSpPlayerID                 inPlayer); 
  411.  
  412.  
  413. /*********************  Group Management  **********************/
  414.  
  415. OSStatus NSpGroup_New(
  416.     NSpGameReference             inGame, 
  417.     NSpGroupID*                    outGroupID);
  418.  
  419. OSStatus NSpGroup_Dispose(
  420.     NSpGameReference             inGame, 
  421.     NSpGroupID                     inGroupID);
  422.  
  423. OSStatus NSpGroup_AddPlayer(
  424.     NSpGameReference             inGame, 
  425.     NSpGroupID                     inGroupID, 
  426.     NSpPlayerID                 inPlayerID);
  427.  
  428. OSStatus NSpGroup_RemovePlayer(
  429.     NSpGameReference             inGame, 
  430.     NSpGroupID                     inGroupID,
  431.     NSpPlayerID                 inPlayerID);
  432.  
  433. OSStatus NSpGroup_GetInfo(
  434.     NSpGameReference             inGame, 
  435.     NSpGroupID                     inGroupID, 
  436.     NSpGroupInfoPtr*            outInfo);
  437.  
  438. void NSpGroup_ReleaseInfo(
  439.     NSpGameReference             inGame, 
  440.     NSpGroupInfoPtr             inInfo);
  441.  
  442. OSStatus NSpGroup_GetEnumeration(
  443.     NSpGameReference             inGame, 
  444.     NSpGroupEnumerationPtr*        outGroups);
  445.  
  446. void NSpGroup_ReleaseEnumeration(
  447.     NSpGameReference             inGame, 
  448.     NSpGroupEnumerationPtr         inGroups);
  449.  
  450.  
  451. /**************************  Utilities  ***************************/
  452.  
  453. void NSpClearMessageHeader(
  454.     NSpMessageHeader*            inMessage);
  455.  
  456. UInt32 NSpGetCurrentTimeStamp(
  457.     NSpGameReference             inGame);
  458.  
  459. NSpAddressReference    NSpConvertOTAddrToAddressReference(
  460.     OTAddress*                    inAddress);
  461.  
  462. OTAddress *NSpConvertAddressReferenceToOTAddr(
  463.     NSpAddressReference         inAddress);
  464.  
  465. void NSpReleaseAddressReference(
  466.     NSpAddressReference         inAddress);
  467.  
  468.  
  469. /************************ Advanced/Async routines ****************/
  470.  
  471. typedef pascal void (*NSpCallbackProcPtr)(
  472.     NSpGameReference             inGame, 
  473.     void*                         inContext, 
  474.     NSpEventCode                 inCode, 
  475.     OSStatus                     inStatus, 
  476.     void*                         inCookie);
  477.  
  478. OSStatus NSpInstallCallbackHandler(
  479.     NSpCallbackProcPtr             inHandler, 
  480.     void*                        inContext);
  481.  
  482.  
  483. typedef pascal Boolean (*NSpJoinRequestHandlerProcPtr)(
  484.     NSpGameReference             inGame, 
  485.     NSpJoinRequestMessage*        inMessage, 
  486.     void*                         inContext,
  487.     Str255                        outReason);
  488.  
  489. OSStatus NSpInstallJoinRequestHandler(
  490.     NSpJoinRequestHandlerProcPtr inHandler, 
  491.     void*                        inContext);
  492.  
  493.  
  494. typedef pascal Boolean (*NSpMessageHandlerProcPtr)(
  495.     NSpGameReference             inGame, 
  496.     NSpMessageHeader*            inMessage, 
  497.     void*                         inContext);
  498.  
  499. OSStatus NSpInstallAsyncMessageHandler(
  500.     NSpMessageHandlerProcPtr     inHandler, 
  501.     void*                        inContext);
  502.  
  503.  
  504.  
  505.  
  506. #ifdef __cplusplus
  507. }
  508. #endif
  509.  
  510. /* NetSprocket Error Codes */
  511. enum
  512. {
  513.     kNSpInitializationFailedErr         = -30360,
  514.     kNSpAlreadyInitializedErr             = -30361,
  515.     kNSpTopologyNotSupportedErr         = -30362,
  516.     kNSpMessageSizeTooBigErr            = -30363,
  517.     kNSpBufferTooSmallErr                 = -30364,
  518.     kNSpReceiveDataErr                     = -30365,
  519.     kNSpProtocolNotAvailableErr         = -30366,
  520.     kNSpInvalidGameRefErr                 = -30367,
  521.     kNSpInvalidNetMessageErr             = -30368,
  522.     kNSpInvalidParameterErr             = -30369,
  523.     kNSpOTNotPresentErr                 = -30370,
  524.     kNSpHostFailedErr                     = -30371,
  525.     kNSpNotHostAddressErr                 = -30372,
  526.     kNSpMemAllocationErr                 = -30373,
  527.     kNSpAlreadyAdvertisingErr             = -30374,
  528.     kNSpNoTypeSpecifiedErr                 = -30375,
  529.     kNSpNotAdvertisingErr                 = -30376,
  530.     kNSpInvalidAddressErr                 = -30377,
  531.     kNSpFreeQExhaustedErr                = -30378,
  532.     kNSpRemovePlayerFailedErr            = -30379,
  533.     kNSpAddressInUseErr                    = -30380,
  534.     kNSpFeatureNotImplementedErr        = -30381,
  535.     kNSpNameRequiredErr                 = -30382,
  536.     kNSpInvalidPlayerIDErr                 = -30383,
  537.     kNSpInvalidGroupIDErr                 = -30384,
  538.     kNSpNoPlayersErr                     = -30385,
  539.     kNSpNoGroupsErr                     = -30386,
  540.     kNSpNoHostVolunteersErr             = -30387,
  541.     kNSpCreateGroupFailedErr             = -30388,
  542.     kNSpAddPlayerFailedErr                 = -30389,
  543.     kNSpInvalidDefinitionErr            = -30390,
  544.     kNSpInvalidProtocolRefErr            = -30391,
  545.     kNSpInvalidProtocolListErr            = -30392,
  546.     kNSpTimeoutErr                        = -30393,
  547.     kNSpGameTerminatedErr                = -30394,
  548.     kNSpConnectFailedErr                = -30395
  549. };
  550.  
  551.  
  552.  
  553. #if PRAGMA_ALIGN_SUPPORTED
  554. #pragma options align=reset
  555. #endif
  556.  
  557. #pragma enumsalwaysint reset
  558.  
  559. #endif